Wie man sieht, habe ich lange Zeit nichts mehr an der Homepage gemacht. Mittlerweile wurde auch die Software die ich nutze deutlich weiter entwickelt und es gibt nun neue Features die ich gerne nutzen möchte.

Noch ein Hinweis: Im Zuge des Updates kam die Überlegung auf, mein privates Wiki auch auf diese Software umzustellen. Vielleicht schreibe ich da dann auch noch mal was zu.

Pelican

Fangen wir mit dem Herzstück an: Pelican

Pelican ist ein statischer Seitengenerator der in Python geschrieben wurde. Der Vorteil ist, dass ich Artikel, wie z.B. diesen hier, in einer Textdatei in Markdown schreibe. Danache starte ich Pelican, dass mir die Seiten dann als statisches HTML generiert.

Bei den Neuerung ist mir direkt die Suche ins Auge gestochen. Hierfür wird ein Plugin genutzt, welches wiederum Stork nutzt. Plugins sind eine Möglichkeit um Pelican zu erweitern.

Um das Layout der Seite anzupassen gibt es verschiedene Themes. Man sich gut hier gut einen Überblick verschaffen. Bei den Themes sollte man aber darauf achten, dass man auch die Featurei, die man nutzen möchte, auch im Theme eingebunden sind. Da die Suchfunktion sehr neu ist, unterstützen bisher nur sehr wenige Themes dieses Feature.

Git

Um alle Dateien zu verwalten habe ich damals erst mal alles in ein git Repo gepackt. Auf meinem Server ist dann ein extra Cron, der das Repo pullt und die statischen Files deployed. Auch nach dem Umbau ist dieses Konstrukt noch aktuell. Es wurde aber deutlich erweitert.

Das Setup

Installation der benötigten Software

Die eigentliche Installation von Pelican erfolgt mit pipx:

pipx install pelican

pipx legt für jedes installierte Pakete eine virtuelle Umgebung an. Da wird noch mehr Pakete benötigen, müssen wir jetzt darauf achten, dass die neuen Pakete in der gleichen virtuellen Umgebung installiert werden. Dafür hat pipx das subcommand inject. Für die Überischtlichkeit, installiere ich jedes Paket hier einzelnd in die neue Umgebung:

pipx inject pelican markdown
pipx inject pelican pelican-search
pipx inject pelican pelican-neighbors
pipx inject pelican pelican-readtime
pipx inject pelican beautifulsoup4

Für die Suche benötigen wir dann noch das oben angesprochene Programm stork. Ich nutze Arch und kann dies einfach mit yay installieren:

yay -Sy stork

Alternativ kann man sich auch div. binaries aus dem git Repo ziehen.

Das Git Repo

Wenn wir von Grund auf anfangen benötigt man als erste ein leeres Repostiory. Dort kann dann eine grundlegende Ordner-/Dateistruktur mit Hilfe von Pelican angelegt werden:

pelican-quickstart

Die Fragen können dann z.B. so beantwortet werden:

Welcome to pelican-quickstart v4.9.1.

This script will help you create a new Pelican-based website.

Please answer the following questions so this script can generate the files needed by Pelican.

> Where do you want to create your new web site? [.]
> What will be the title of this web site? Meine neue Seite
> Who will be the author of this web site? Stefan Hellmann
> What will be the default language of this web site? [en] de
> Do you want to specify a URL prefix? e.g., https://example.com (Y/n) y
> What is your URL prefix? (see above example; no trailing slash) https://www.hellmann-it.de
> Do you want to enable article pagination? (Y/n) y
> How many articles per page do you want? [10]
> What is your time zone? [Europe/Rome] Europe/Berlin
> Do you want to generate a tasks.py/Makefile to automate generation and publishing? (Y/n) n
Done. Your new project is available at /home/user/git/website

In der Standarkonfiguration erzeugen wir so zwei Ordner und zwei Dateien. Im Ordner content erstellen wir dann nach die eigentlichen Artikel. Wir man oben bei der Installation der Softwre gesehen hat, habe ich extra markdown installiert. Damit man dies in Verbindung mit Pelican nutzen kann, muss das Paket extra installiert werden. Alternativ kann mann die Artikel aber auch in reStructuredText format erstellen.

Für weitere Plugins und das Theme erstellen wir dann in unserem Git Repository noch weitere Ordner:

mkdir themes pelican-plugins

Nun können wir das Theme und ein Plugin was wir noch benötigen als git submodule hinzufügen:

git submodule add https://github.com/pelican-themes/papyrus.git themes/papyrus
git submodule add https://github.com/ingwinlu/pelican-toc.git pelican-plugins/pelican-toc

Für das Papyrus Theme gibt es einen Vorschlag für eine (pelicaconf.py)[https://github.com/pelican-themes/papyrus#settings] . Diese kann fast 1 zu 1 übernommen werden. Um Fehler zu verhindern, sollten die folgenden zwei Variablen aus der Config entfernt werden. Die Systax ist anders und die Angaben dort sind nicht nötig, da sie die default Einstellungen sind.

# Site search plugin
SEARCH_MODE = "output"
SEARCH_HTML_SELECTOR = "main"

Damit steht dann auch schon das komplette Setup fertig.

Helferlein

Um mir die Arbeit etwas zu erleichtern habe ich mir im root des Git Repos noch drei Scripte abgelegt:

test.sh

1
2
3

#!/bin/bash
pelican --autoreload --listen --ignore-cache -v -t themes/papyrus-shell -d \
-e RELATIVE_URLS=true -e SITEURL=\"http://127.0.0.1:8000\" -D

Um zu sehen wie ein neuer Artikel aussieht, starte ich dieses Script und kann mir die komplette Homepage local über https://127.0.0.1:8000 anschauen.

build_live.sh

1
2

#!/bin/bash
pelican --ignore-cache -d

Wenn ich dann fertig bin, erzeuge ich mir mit diesem Script den Output, der nachher von Webserver ausgeliefert wird. Die Dateien liegen dann im Ordner output.

deploy_live.sh

1
2
3
4
5
6
7
8
9

#!/bin/bash
if [ -d /srv/htdocs/homepage ]; then
    if [ -f /srv/htdocs/homepage.tar.gz ]; then
        rm /srv/htdocs/homepage.tar.gz
    fi
    tar czf /srv/htdocs/homepage.tar.gz /srv/htdocs/homepage/
    rm -rf /srv/htdocs/homepage/*
    rsync --progress -r output/* /srv/htdocs/homepage/
fi

Dieses Script nutze ich dann auf dem Server um den generierten Output zu deployen.

Fazit

Bis alles sauebr zusammen funktioniert hat musste ich ein wenig Try & Error betreiben. Am Theme habe ich noch einige Anpassungen vorgenommen. Jetzt klappt aber alles wunderbar.

Da der Inhalt so einfach gepflegt werden kann, überlege ich, das Wiki das ich bisher für private Notizen nutze auch auf Pelican umzustellen. Gerade die Suche scheint hier echt gut zu funktionieren.

P.S.

In letzter Zeit hatte ich immer wieder Probleme stork unter z.B. Debian zu isntallieren. Nachdem ich dann die Doku mal gelesen habe, ist das eigentlich ganz simpel:

cargo install stork-search --locked

Die binary wird dann im Homedirectory unter ~/.cargo/bin abgelegt. Dies muss dann einfach der APTH Variable hinzugfügt werden.